Clarify that `cargo doc --no-deps` is cumulative and won’t delete prev #15800

ojuschugh1 · 2025-08-03T10:51:49Z

What does this PR try to resolve?

clarifies that cargo doc --no-deps will not delete previously-built dependency docs, and points users to cargo clean --doc or manual deletion if they want a truly “fresh” doc set. This pr fixed #15728

How to test and review this PR?

No testing required.

rustbot · 2025-08-03T10:51:54Z

r? @epage

rustbot has assigned @epage.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

weihanglo · 2025-08-03T14:53:44Z

src/doc/man/cargo-doc.md

@@ -31,6 +31,15 @@ option.

 {{#option "`--no-deps`" }}
 Do not build documentation for dependencies.
+
+**Note:** Documentation is _cumulative_. If you’ve already run


The cumulative behavior is not specific to the --no-deps flag. I would personally prefer to seeing this in DESCRIPTION than here.

Sure, I have added this information in DESCRIPTION.

weihanglo · 2025-08-03T14:54:21Z

src/doc/man/cargo-doc.md

+old dependency docs. To remove them, you can either:
+
+1. Run `cargo clean --doc` before `cargo doc --no-deps`, or  
+2. Manually delete the unwanted folders under `target/doc/`.


Why did this call out manually? Anything cargo clean --doc can't achieve?

This hasn't been addressed.

This has been fixed, thanks !

weihanglo

Not sure why putting this in draft again. Ready for review?

weihanglo · 2025-08-04T18:19:36Z

src/doc/man/cargo-doc.md

+old dependency docs. To remove them, you can either:
+
+1. Run `cargo clean --doc` before `cargo doc --no-deps`, or  
+2. Manually delete the unwanted folders under `target/doc/`.


This hasn't been addressed.

weihanglo · 2025-08-04T18:51:09Z

src/doc/man/cargo-doc.md

+simply prevent *rebuilding* those pages—they will remain until you
+explicitly clean them up.
+
+### Removing old docs


I don't feel like "Remvoing old docs" requires its own paragraph. We should probably put less doc on this.

Perhaps in combination of the previous paragraph, we do this

Documentation generation is cumulative: existing doc files in the target directory are preserved across different cargo doc invocations. To remove existing generated docs, pass --doc to {{man "cargo-clean" 1}}.

ojuschugh1 · 2025-08-04T19:29:28Z

Not sure why putting this in draft again. Ready for review?

One test failed for docs so i am fixing it and then i will push the changes again.

weihanglo

Normally I would suggest splitting the second commit (fixing lint error) into its own pull request, though it is too much a hassle here atm so going to merge it as-is. I would still encourage fixing unrelated errors separately in the future.

Thanks for the contribution anyway.

weihanglo

Found some more stuff to change.

Given that, I would suggest doing this in a separate PR.

src/doc/man/cargo-doc.md

These were caught with the latest nightly This was pulled from rust-lang#15800

### What does this PR try to resolve? Unblock CI ### How to test and review this PR? ### Notes These were caught with the latest nightly This was pulled from #15800

weihanglo

Thanks!

Update cargo 23 commits in 840b83a10fb0e039a83f4d70ad032892c287570a..9a0712751ca9444775c7352d3c942a155b656437 2025-07-30 13:59:19 +0000 to 2025-08-15 20:30:47 +0000 - Fixes error while running the cargo clippy --all-targets -- -D warning (rust-lang/cargo#15843) - Clarify that `cargo doc --no-deps` is cumulative and won’t delete prev (rust-lang/cargo#15800) - docs: Formatting and cross-linking to build-dir/target-dir docs (rust-lang/cargo#15840) - Stabilize `build.build-dir` (rust-lang/cargo#15833) - make resolve features public for cargo-as-a-library (rust-lang/cargo#15835) - chore(deps): bump slab from 0.4.10 to 0.4.11 (rust-lang/cargo#15832) - chore: remove x86_64-apple-darwin from CI and tests (rust-lang/cargo#15831) - chore(deps): update msrv (3 versions) to v1.87 (rust-lang/cargo#15819) - perf(package): Always reuse the workspace's target-dir (rust-lang/cargo#15783) - More helpful error for invalid cargo-features = [] (rust-lang/cargo#15781) - Add initial integration for `--json=timings` behing `-Zsection-timings` (rust-lang/cargo#15780) - add is_inherited methods to InheritableDependency and InheritableField (rust-lang/cargo#15828) - chore(deps): update compatible (rust-lang/cargo#15804) - docs(unstable): Link out to the Plumbing commands effort (rust-lang/cargo#15821) - chore(deps): update cargo-semver-checks to v0.43.0 (rust-lang/cargo#15825) - test(build-std): relax the thread name assertion (rust-lang/cargo#15822) - chore(deps): update msrv (1 version) to v1.89 (rust-lang/cargo#15815) - Update semver tests for 1.89 (rust-lang/cargo#15816) - Accessing each build script's `OUT_DIR` and in the correct order (rust-lang/cargo#15776) - chore: bump to 0.92.0; update changelog (rust-lang/cargo#15807) - docs: `-Zpackage-workspace` has been stabilized (rust-lang/cargo#15808) - chore(deps): update rust crate cargo_metadata to 0.21.0 (rust-lang/cargo#15795) - docs(build-rs): Fix broken intra-doc links (rust-lang/cargo#15810) r? ghost

Update cargo 28 commits in 840b83a10fb0e039a83f4d70ad032892c287570a..71eb84f21aef43c07580c6aed6f806a6299f5042 2025-07-30 13:59:19 +0000 to 2025-08-17 17:18:56 +0000 - update tests to match lint message changes from #140794 (rust-lang/cargo#15849) - chore: downgrade to [email protected] (rust-lang/cargo#15851) - Reorder `lto` options in profiles.md (rust-lang/cargo#15841) - feat(unstable): add -Zbuild-analysis unstable feature (rust-lang/cargo#15845) - refactor(unstable): group stabilized features (rust-lang/cargo#15846) - Fixes error while running the cargo clippy --all-targets -- -D warning (rust-lang/cargo#15843) - Clarify that `cargo doc --no-deps` is cumulative and won’t delete prev (rust-lang/cargo#15800) - docs: Formatting and cross-linking to build-dir/target-dir docs (rust-lang/cargo#15840) - Stabilize `build.build-dir` (rust-lang/cargo#15833) - make resolve features public for cargo-as-a-library (rust-lang/cargo#15835) - chore(deps): bump slab from 0.4.10 to 0.4.11 (rust-lang/cargo#15832) - chore: remove x86_64-apple-darwin from CI and tests (rust-lang/cargo#15831) - chore(deps): update msrv (3 versions) to v1.87 (rust-lang/cargo#15819) - perf(package): Always reuse the workspace's target-dir (rust-lang/cargo#15783) - More helpful error for invalid cargo-features = [] (rust-lang/cargo#15781) - Add initial integration for `--json=timings` behing `-Zsection-timings` (rust-lang/cargo#15780) - add is_inherited methods to InheritableDependency and InheritableField (rust-lang/cargo#15828) - chore(deps): update compatible (rust-lang/cargo#15804) - docs(unstable): Link out to the Plumbing commands effort (rust-lang/cargo#15821) - chore(deps): update cargo-semver-checks to v0.43.0 (rust-lang/cargo#15825) - test(build-std): relax the thread name assertion (rust-lang/cargo#15822) - chore(deps): update msrv (1 version) to v1.89 (rust-lang/cargo#15815) - Update semver tests for 1.89 (rust-lang/cargo#15816) - Accessing each build script's `OUT_DIR` and in the correct order (rust-lang/cargo#15776) - chore: bump to 0.92.0; update changelog (rust-lang/cargo#15807) - docs: `-Zpackage-workspace` has been stabilized (rust-lang/cargo#15808) - chore(deps): update rust crate cargo_metadata to 0.21.0 (rust-lang/cargo#15795) - docs(build-rs): Fix broken intra-doc links (rust-lang/cargo#15810)

rustbot assigned epage Aug 3, 2025

rustbot added A-documenting-cargo-itself Area: Cargo's documentation S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Aug 3, 2025

ojuschugh1 force-pushed the document-cargo-doc-no-deps branch from b5fbe40 to 465c2af Compare August 3, 2025 11:28

rustbot added the A-cli-help Area: built-in command-line help label Aug 3, 2025

weihanglo reviewed Aug 3, 2025

View reviewed changes

ojuschugh1 force-pushed the document-cargo-doc-no-deps branch 3 times, most recently from 892bd12 to 55cb10b Compare August 4, 2025 18:53

ojuschugh1 marked this pull request as draft August 4, 2025 18:53

rustbot removed the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Aug 4, 2025

weihanglo reviewed Aug 4, 2025

View reviewed changes

ojuschugh1 force-pushed the document-cargo-doc-no-deps branch from 55cb10b to 330f1de Compare August 4, 2025 19:27

ojuschugh1 force-pushed the document-cargo-doc-no-deps branch 2 times, most recently from 4986b8f to b29b82e Compare August 4, 2025 19:52

rustbot added the A-build-scripts Area: build.rs scripts label Aug 4, 2025

ojuschugh1 force-pushed the document-cargo-doc-no-deps branch from b29b82e to 004fa29 Compare August 4, 2025 20:00

rustbot added the A-configuration Area: cargo config files and env vars label Aug 4, 2025

ojuschugh1 force-pushed the document-cargo-doc-no-deps branch 2 times, most recently from 23e20fc to 7e44417 Compare August 4, 2025 20:48

ojuschugh1 marked this pull request as ready for review August 4, 2025 21:12

rustbot added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Aug 4, 2025

ojuschugh1 requested a review from weihanglo August 4, 2025 21:12

weihanglo approved these changes Aug 5, 2025

View reviewed changes

weihanglo requested changes Aug 5, 2025

View reviewed changes

src/doc/man/cargo-doc.md Outdated Show resolved Hide resolved

epage pushed a commit to epage/cargo that referenced this pull request Aug 5, 2025

docs(build-rs): Fix broken intra-doc links

c0c256b

These were caught with the latest nightly This was pulled from rust-lang#15800

epage mentioned this pull request Aug 5, 2025

docs(build-rs): Fix broken intra-doc links #15810

Merged

weihanglo changed the title ~~Clarify that cargo doc --no-deps is cumulative and won’t delete prev issue #15728~~ Clarify that cargo doc --no-deps is cumulative and won’t delete prev Aug 15, 2025

weihanglo approved these changes Aug 15, 2025

View reviewed changes

weihanglo enabled auto-merge August 15, 2025 19:41

weihanglo added this pull request to the merge queue Aug 15, 2025

Merged via the queue into rust-lang:master with commit d1bbe63 Aug 15, 2025
23 checks passed

rustbot removed the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Aug 15, 2025

weihanglo mentioned this pull request Aug 16, 2025

Update cargo rust-lang/rust#145478

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Clarify that `cargo doc --no-deps` is cumulative and won’t delete prev #15800

Clarify that `cargo doc --no-deps` is cumulative and won’t delete prev #15800

ojuschugh1 commented Aug 3, 2025

Uh oh!

rustbot commented Aug 3, 2025

Uh oh!

weihanglo Aug 3, 2025

Uh oh!

ojuschugh1 Aug 4, 2025

Uh oh!

weihanglo Aug 3, 2025

Uh oh!

weihanglo Aug 4, 2025

Uh oh!

ojuschugh1 Aug 4, 2025

Uh oh!

weihanglo left a comment

Uh oh!

weihanglo Aug 4, 2025

Uh oh!

weihanglo Aug 4, 2025

Uh oh!

ojuschugh1 Aug 4, 2025

Uh oh!

ojuschugh1 commented Aug 4, 2025

Uh oh!

weihanglo left a comment

Uh oh!

weihanglo left a comment

Uh oh!

Uh oh!

weihanglo left a comment

Uh oh!

Uh oh!

Uh oh!

Clarify that cargo doc --no-deps is cumulative and won’t delete prev #15800

Clarify that cargo doc --no-deps is cumulative and won’t delete prev #15800

Conversation

ojuschugh1 commented Aug 3, 2025

What does this PR try to resolve?

How to test and review this PR?

Uh oh!

rustbot commented Aug 3, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

weihanglo left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ojuschugh1 commented Aug 4, 2025

Uh oh!

weihanglo left a comment

Choose a reason for hiding this comment

Uh oh!

weihanglo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

weihanglo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Clarify that `cargo doc --no-deps` is cumulative and won’t delete prev #15800

Clarify that `cargo doc --no-deps` is cumulative and won’t delete prev #15800